设备影子

物联网平台提供设备影子功能，用于缓存设备状态。设备在线时，可以直接获取云端指令；设备离线时，上线后可以主动拉取云端指令。 设备影子是一个 JSON 文档，用于存储设备上报状态、应用程序期望状态信息。 每个设备有且只有一个设备影子，设备可以通过MQTT获取和设置设备影子来同步状态，该同步可以是影子同步给设备，也可以是设备同步给影子。

应用场景

• 场景1：网络不稳定，设备频繁上下线。 由于网络不稳定，设备频繁上下线。应用程序发出需要获取当前的设备状态请求时，设备掉线，无法获取设备状态，但下一秒设备又连接成功，应用程序无法正确发起请求。 使用设备影子机制存储设备最新状态，一旦设备状态产生变化，设备会将状态同步到设备影子。应用程序在请求设备当前状态时，只需要获取影子中的状态即可，不需要关心设备是否在线。

• 场景2：多程序同时请求获取设备状态。 如果设备网络稳定，很多应用程序请求获取设备状态，设备需要根据请求响应多次，即使响应的结果是一样的，设备本身处理能力有限，无法负载被请求多次的情况。 使用设备影子机制，设备只需要主动同步状态给设备影子一次，多个应用程序请求设备影子获取设备状态，即可获取设备最新状态，做到应用程序和设备的解耦。

• 场景3：设备掉线。

  • 设备网络不稳定，导致设备频繁上下线，应用程序发送控制指令给设备时，设备掉线，指令无法下达到设备。
    • 通过QoS=1实现，但是该方法对于服务端的压力比较大，一般不建议使用。
    • 使用设备影子机制，应用程序发送控制指令，指令携带时间戳保存在设备影子中。当设备掉线重连时，获取指令并根据时间戳确定是否执行。
  • 设备真实掉线，指令发送失败。设备再上线时，设备影子功能通过指令加时间戳的模式，保证设备不会执行过期指令。

查看与更新设备影子

您可以在设备详情页，查看设备影子信息，更新设备影子状态。

操作步骤：

1.登陆平台设备管理界面

2.单击对应设备的查看设备列表按钮, 进入设备列表界面

3.单击对应设备的详情按钮, 进入设备详情页

4.单击设备影子

5.单击编辑镜像，填入期望设备状态。设备影子文档格式，请参见设备影子JSON详解。

• 设备在线时，设备影子保存期望状态，设备通过订阅Topic直接获得期望状态。
• 设备离线时，设备影子缓存期望状态，设备上线后，主动从云端拉取最新期望状态。

设备影子JSON详解

设备影子JSON文档示例：

{
    "deviceId":10218769,
    "createTime":1586830856,
    "connectionSta te":0,
    "properties":{
        "timestamp":1586832673,
        "version":1,
        "state":{
            "desired":{
                "color":"red"
            },
            "reported":{
                "color":"green"
            }
        },
        "metadata":{
            "desired":{
                "color":1586832673
            },
            "reported":{
                "color":1586832673
            }
        }
    }
}

JSON属性说明

说明

设备影子支持数组。更新数组时必须全量更新，不能只更新数组的某一部分。
更新数组数据示例：

初始状态：
{
    "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}

更新：
{
    "desired" : { "colors" : ["RED"] }
}

最终状态：
{
    "desired" : { "colors" : ["RED"] }
}

设备影子数据流

设备影子数据通过Topic进行流转。本文介绍设备影子数据流转，包括：设备上报状态到设备影子，应用程序更改设备状态，设备离线再上线后主动获取设备影子信息，和设备端请求删除设备影子中的属性信息。

设备影子Topic

物联网平台已为每个设备预定义了四个Topic，用于实现数据流转。您可以直接使用。

• shadow/update/pid/${产品ID}/devkey/${设备ID} 设备发布消息到此Topic。物联网平台收到该Topic的消息后，将消息中的状态更新到设备影子中。

• shadow/update/resp/pid/${产品ID}/devkey/${设备ID} 设备订阅此topic获取更新结果

• shadow/get/${产品ID}/${设备ID} 设备向此topic发起获取设备影子请求

• shadow/get/resp/${产品ID}/${设备ID} 设备订阅此topic获取请求结果, 应用程序更新设备影子通过此topic下发给设备

使用示例

以下章节中，以某个具体设备为例，说明设备、设备影子以及应用程序之间的通信。

示例中，产品ID是100657；设备ID是10218769。设备以QoS=1发布消息和订阅两个设备影子Topic: shadow/update/resp/pid/100657/devkey/10218769, shadow/get/resp/pid/100657/devkey/10218769。

示例主要讲解四大部分内容：设备主动上报状态，应用程序改变设备状态，设备主动获取影子内容，和设备主动删除影子属性。

一、设备主动上报状态

设备在线时，主动上报设备状态到影子，应用程序主动获取设备影子状态。

1.当设备上线时，使用Topic shadow/update/pid/100657/devkey/10218769上报最新状态到影子。 发送的JSON消息格式：

{
  "method": "update", 
  "state": {
    "reported": {
      "color": "red"
    }
  }, 
  "version": 1
}

上报参数说明

2.设备影子接收到设备上报的状态数据后，更新影子文档

{
    "deviceId":10218769,
    "createTime":1586830856,
    "connectionState":1,
    "properties":{
        "timestamp":1586830856,
        "version":2,
        "state":{
            "desired":{
            },
            "reported":{
                "color":"red"
            }
        },
        "metadata":{
            "desired":{

            },
            "reported":{
                "color":1586833593
            }
        }
    }
}

3.影子文档更新后，设备影子会返回结果给设备，即发送消息到设备订阅的Topic: shadow/update/resp/pid/100657/devkey/10218769 中。

• 若更新成功，发送到该Topic中的消息为：

   {
       "method": "reply", 
       "payload": {
           "status": "success", 
           "version": 1
       }, 
       "timestamp": 1586833593
   }
  

• 若更新失败，发送到该Topic中的消息为：

    {
        "method": "reply", 
        "payload": {
            "status": "error", 
            "content": {
            "errorcode": "${errorcode}", 
            "errormessage": "${errormessage}"
        },
        "timestamp": 1469564576
    }
  

  错误码说明

二、通过界面改变设备状态

用户通过界面设备影子模块下发期望状态给设备影子，设备影子再将文档下发给设备端。设备根据影子更新状态，并上报最新状态至影子。

1.用户通过界面设备影子模块下发消息要求更改设备状态，例如要求将设备的color属性值改为green。

2.设备影子接收到更新请求，更新其影子文档为：

{
     "deviceId":10218769,
    "createTime":1586830856,
    "connectionState":1,
    "properties":{
        "timestamp":1586830856,
        "version":3,
        "state":{
            "desired":{
                "color":"green"
            },
            "reported":{
                "color":"red"
            }
        },
        "metadata":{
            "desired":{
                "color":1586836789
            },
            "reported":{
                "color":1586833593
            }
        }
    }

3.设备影子更新完成后，发送返回结果到Topic: shadow/get/resp/pid/100657/devkey/10218769中。返回结果信息构成由设备影子决定。

{
    "method":"reply",
    "payload":{
    "status": "success",
        "state": {
            "desired": {
                "color": "green", 
            }, 
            "reported": {
                "color": "red"
            }
        },
        "metadata": {
            "desired": {
                "color": {
                    "timestamp": 1469564492
                }, 
            }, 
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }
        }
    }, 
    "timestamp": 1469564492, 
    "version": 1 
}

4.如果设备在线，并且订阅了Topic shadow/get/resp/pid/100657/devkey/10218769，则会立即收到消息。收到消息后，根据请求文档中desired的值，将设备color属性变成green。

设备更新完状态后，上报最新状态到物联网平台。

{
  "method": "update", 
  "state": {
    "reported": {
      "color": "green"
    }
  }, 
  "version": 4
}

三、设备主动获取影子内容

设备再次上线后，将主动获取设备影子内容。

1.设备主动发送以下消息到Topic shadow/get/pid/100657/devkey/10218769中，请求获取设备影子中保存的最新状态。

{
"method": "get"
}

2.当设备影子收到这条消息后，发送最新状态到Topic: shadow/get/resp/pid/100657/devkey/10218769。设备通过订阅该Topic获取最新状态。消息内容如下：

{
    "method":"reply",
    "payload":{
    "status": "success",
        "state": {
            "desired": {
                "color": "green", 
            }, 
            "reported": {
                "color": "red"
            }
        },
        "metadata": {
            "desired": {
                "color": {
                    "timestamp": 1469564492
                }, 
            }, 
            "reported": {
                "color": {
                    "timestamp": 1469564492
                }
            }
        }
    }, 
    "timestamp": 1469564492, 
    "version": 1 
}

四、设备主动删除影子属性

若设备端已经是最新状态，设备端可以主动发送指令，删除设备影子中保存的某条属性状态。

• 删除影子中某一属性。

{
  "method": "delete", 
  "state": {
    "reported": {
      "color": "null", 
      "temperature": "null"
    }
  }, 
  "version": 1
}

• 删除影子全部属性。

// 删除影子全部属性
{
  "method": "delete", 
  "state": {
    "reported": "null"
  }, 
  "version": 1
}